@abstractframework/continuum 0.3.2 → 0.4.0

package/README.md

@@ -72,7 +72,11 @@ abstractcontinuum
 ```
 
 Open `http://localhost:3002` and sign in with a gateway user and token (the
-connection badge at the bottom of the sidebar). The token is exchanged
+connection badge at the bottom of the sidebar). When your gateway manages
+Continuum (the gateway console's **Apps** screen), open it from there
+instead: the gateway serves it at `/apps/continuum/` on its own port, so a
+remote or headless machine needs one port and one tunnel for the console and
+every app. The token is exchanged
 server-side for an HttpOnly session cookie and never stored in the browser.
 
 The server is configured with launch flags or saved settings (full list in
@@ -85,8 +89,9 @@ abstractcontinuum config get                   # every setting and where it come
 ```
 
 - `--port` (default `3002`), `--host` (default `127.0.0.1`)
-- `--gateway-url` — the gateway this deployment talks to (default
-  `http://127.0.0.1:8080`)
+- `--gateway-url` (aliases `--gateway`, `--url`) — the gateway this
+  deployment talks to (default: the gateway installed on this computer, from
+  `~/.abstractframework/gateway.json`, else `http://127.0.0.1:8080`)
 - `--hub-url` / `--hub-seat` / `--hub-token-file` — the agora hub, your seat
   and its key for the Team page. The hub seat is also on the Settings page.
 

package/bin/cli.js

@@ -6,23 +6,26 @@
  * shared app-origin session proxy (first-party cookies + CSRF; tokens never
  * in URLs) — the same @abstractframework/app-server module the observer,
  * flow, and code apps converge on.
+ *
+ * Mountable under the gateway at /apps/continuum/ (the kit's mount
+ * contract): every response announces `X-AbstractFramework-App:
+ * continuum; mount=1`, the page gets `<base href="<base path>/">` and
+ * `base_path`, and every "is this the operator's own computer?" check reads
+ * the kit's requestContext (bin/request_gate.js). Served at `/` on its own
+ * port it works exactly as before.
  */
 
-import * as http from 'http';
-import { readFileSync, existsSync, statSync } from 'fs';
-import { join, extname, dirname } from 'path';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { createGatewaySessionProxy } from '@abstractframework/app-server';
-import { createHubProxy } from './hub_proxy.js';
+import { createContinuumServer } from './server.js';
 import {
   SETTINGS,
   SOURCE_WORDS,
   apply_session_proxy_gates,
   createLiveSettings,
-  createSettingsRoute,
   default_settings_path,
   display_value,
-  expand_home,
   parse_args,
   read_settings_file,
   resolve_settings,
@@ -53,6 +56,10 @@ function help_text() {
     const def = spec.type === 'bool' ? 'off' : spec.default === '' ? 'none' : String(spec.default);
     lines.push(col(left, spec.help));
     lines.push(`${' '.repeat(32)}default ${def}; setting ${spec.key}`);
+    if (spec.key === 'gateway_url') {
+      lines.push(`${' '.repeat(32)}also --gateway <url>, --url <url>; with none set, the gateway`);
+      lines.push(`${' '.repeat(32)}installed on this computer (~/.abstractframework/gateway.json)`);
+    }
     if (spec.key === 'hub_token') {
       lines.push(col('--hub-token-file <path>', 'read the hub token from a file (never printed)'));
       lines.push(`${' '.repeat(32)}setting hub_token`);
@@ -159,169 +166,18 @@ const PORT = AT_START.port.value;
 // binds are an explicit deployment choice (--host).
 const HOST = AT_START.host.value;
 const DEFAULT_GATEWAY_URL = AT_START.gateway_url.value;
-
 // The session proxy reads its hardening gates from the environment only;
 // hand it the resolved values (flag > setting > environment > default).
 apply_session_proxy_gates(AT_START, process.env);
 
-const MIME_TYPES = {
-  '.html': 'text/html',
-  '.js': 'application/javascript',
-  '.css': 'text/css',
-  '.json': 'application/json',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.svg': 'image/svg+xml',
-  '.ico': 'image/x-icon',
-  '.webmanifest': 'application/manifest+json',
-};
-
-function getMimeType(filePath) {
-  const ext = extname(filePath).toLowerCase();
-  return MIME_TYPES[ext] || 'application/octet-stream';
-}
-
-// Content-Security-Policy for the app document (security adversary P1
-// 2026-07-16): untrusted markdown (channel files, messages, attachments)
-// renders in this app, and standard markdown allows remote images — a
-// crafted ![](https://attacker/beacon.png) would beacon the operator's IP
-// and read-timing to an external host the moment a preview opens. img-src
-// 'self' data: kills that class app-wide. script-src 'self' is a backstop
-// belt (the renderer already cannot emit script). ws:/wss: are needed
-// because 'self' does not reliably cover scheme-different WebSocket dials;
-// only our own bundle can open sockets (script-src), so this stays tight.
-const CSP = [
-  "default-src 'self'",
-  "script-src 'self'",
-  "style-src 'self' 'unsafe-inline'", // React style={} attributes
-  "img-src 'self' data:",
-  "font-src 'self' data:",
-  "connect-src 'self' ws: wss:",
-  "object-src 'none'",
-  "base-uri 'self'",
-  "form-action 'self'",
-  "frame-ancestors 'none'",
-].join('; ');
-
-function serveFile(res, filePath) {
-  try {
-    if (!existsSync(filePath) || !statSync(filePath).isFile()) {
-      return false;
-    }
-    const content = readFileSync(filePath);
-    const mime = getMimeType(filePath);
-    const headers = {
-      'Content-Type': mime,
-      'Cache-Control': 'no-cache',
-      'X-Content-Type-Options': 'nosniff',
-    };
-    // CSP is a document policy — attach it where a document loads.
-    if (mime === 'text/html') headers['Content-Security-Policy'] = CSP;
-    res.writeHead(200, headers);
-    res.end(content);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// Cookies abstractcontinuum_gateway_* and header x-abstractcontinuum-csrf
-// derive from appId.
-const gatewaySessionProxy = createGatewaySessionProxy({
-  appId: 'abstractcontinuum',
-  defaultGatewayUrl: DEFAULT_GATEWAY_URL,
-});
-
-// Team page transport: /api/hub/* forwards an allowlisted hub API subset
-// with the OPERATOR seat's key attached server-side (proposal c1692,
-// agency contract c1696 — authorship stays the operator's own).
-// Every hub setting is a getter: a seat saved on the Settings page or with
-// `abstractcontinuum config set` applies without a restart.
-const hubProxy = createHubProxy({
-  hubUrl: () => settings.value('hub_url'),
-  seat: () => settings.value('hub_seat'),
-  keysPath: () => expand_home(settings.value('hub_keys')),
-  token: () => settings.value('hub_token'),
-  allowRemote: () => settings.value('hub_allow_remote'),
-});
-
-// The Settings page's door to this server's own settings (hub seat).
-const settingsRoute = createSettingsRoute({ live: settings });
-
-const server = http.createServer((req, res) => {
-  // Parse against a FIXED base: a malformed Host header (e.g. "a b") makes
-  // new URL throw synchronously, which would kill the whole process from
-  // one bad request (adversarial P1 2026-07-13). The host plays no role in
-  // routing here — only the pathname does.
-  let pathname = '/';
-  let search = '';
-  try {
-    const u = new URL(req.url, 'http://local');
-    pathname = u.pathname;
-    search = u.search;
-  } catch {
-    res.writeHead(400);
-    res.end('Bad Request');
-    return;
-  }
-
-  if (settingsRoute.handle(req, res, pathname)) {
-    return;
-  }
-
-  if (hubProxy.handle(req, res, pathname, search)) {
-    return;
-  }
-
-  if (gatewaySessionProxy.handle(req, res, pathname)) {
-    return;
-  }
-
-  if (pathname.includes('..')) {
-    res.writeHead(400);
-    res.end('Bad Request');
-    return;
-  }
-
-  if (pathname === '/' || pathname === '') {
-    pathname = '/index.html';
-  }
-
-  const filePath = join(DIST_DIR, pathname);
-  if (serveFile(res, filePath)) return;
-  if (serveFile(res, filePath + '.html')) return;
-
-  // SPA fallback
-  if (serveFile(res, join(DIST_DIR, 'index.html'))) return;
-
-  res.writeHead(404);
-  res.end('Not Found');
-});
-
-// Live hub updates: relay browser WebSockets to the hub with the seat key
-// attached server-side (operator c2240 — realtime, not 5s polling).
-server.on('upgrade', (req, socket, head) => {
-  // F7 (dm-99 tail): a raw upgrade socket with no 'error' listener is a
-  // process-killer (browser aborts mid-handshake raise uncaught 'error');
-  // and a rejected relay promise without .catch is an unhandled rejection.
-  socket.on('error', () => {
-    try { socket.destroy(); } catch { /* already gone */ }
-  });
-  void hubProxy.handleUpgrade(req, socket, head).then((handled) => {
-    if (!handled) socket.destroy();
-  }).catch(() => {
-    try { socket.destroy(); } catch { /* already gone */ }
-  });
-});
+const server = createContinuumServer({ settings, distDir: DIST_DIR });
 
 server.listen(PORT, HOST, () => {
   const seat = AT_START.hub_seat;
   console.log(`
 AbstractContinuum is running.
   Local:    http://localhost:${PORT}
-  Gateway:  ${DEFAULT_GATEWAY_URL}
+  Gateway:  ${DEFAULT_GATEWAY_URL} (${SOURCE_WORDS[AT_START.gateway_url.source]})
   Hub seat: ${seat.value} (${SOURCE_WORDS[seat.source]})
   Settings: ${SETTINGS_PATH}
 `);

package/bin/hub_proxy.js

@@ -20,6 +20,11 @@
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import { APP_IDENTITY_HEADER, MountRequestError, identityHeaderValue, rejectUpgrade } from '@abstractframework/app-server';
+import { request_gate } from './request_gate.js';
+
+/** The gateway catalog id this server announces (`/apps/continuum/`). */
+export const APP_ID = 'continuum';
 
 /** Console version for the hub's X-Agora-Client handshake (read once at
  *  boot; "0.0.0" only if package.json is unreadable — the header's job is
@@ -190,30 +195,6 @@ const HUB_ROUTES = [
   { method: 'DELETE', re: /^\/channels\/[A-Za-z0-9_.:-]+\/reputation\/[A-Za-z0-9_.-]+$/ },
 ];
 
-/**
- * Cross-origin refusal (adversary P0, 2026-07-15): the loopback peer gate
- * defends against REMOTE peers, but the browser itself is a loopback peer —
- * a hostile page the operator visits can fire cross-origin fetches and
- * WebSocket handshakes at this proxy (WS handshakes skip CORS preflight
- * entirely), and the seat key rides server-side. Rule: when the browser
- * declares an Origin, it must match the Host the request was addressed to;
- * absent Origin (curl, scripts, same-origin GET navigations) passes — a
- * browser NEVER omits Origin on cross-origin fetch/WS, so the vector this
- * closes cannot dodge the check.
- */
-function origin_allowed(req) {
-  const origin = String((req.headers && req.headers.origin) || '').trim();
-  if (!origin) return true;
-  let parsed;
-  try {
-    parsed = new URL(origin);
-  } catch {
-    return false;
-  }
-  const host = String((req.headers && req.headers.host) || '').trim().toLowerCase();
-  return Boolean(host) && parsed.host.toLowerCase() === host;
-}
-
 function read_seat_key(keys_path, hub_url, seat, token) {
   // An explicit token (--hub-token / --hub-token-file / the hub_token
   // setting, resolved by bin/settings.js) wins over the key store.
@@ -427,13 +408,20 @@ export function createHubProxy(opts) {
       socket.on('error', () => {
         try { socket.destroy(); } catch { /* already gone */ }
       });
+      // Same gate as the HTTP surface (the BROWSER's address, which behind
+      // the gateway is the forwarded one), PLUS the origin gate against the
+      // host the browser addressed — WS handshakes have no CORS preflight,
+      // so without it any page the operator visits could open this relay
+      // and read/write as the operator seat (adversary P0).
+      let gate;
+      try {
+        gate = request_gate(req);
+      } catch (e) {
+        if (!(e instanceof MountRequestError)) throw e;
+        rejectUpgrade(socket, e.status, e.message);
+        return true;
+      }
       try {
-        // Same unforgeable peer gate as the HTTP surface, PLUS the origin
-        // gate — WS handshakes have no CORS preflight, so without it any
-        // page the operator visits could open this relay and read/write
-        // as the operator seat (adversary P0).
-        const peer = String(req.socket && req.socket.remoteAddress ? req.socket.remoteAddress : '');
-        const loopback = peer === '127.0.0.1' || peer === '::1' || peer === '::ffff:127.0.0.1' || peer === '';
         const allow_remote = cfg().allow_remote;
         const seat_key = key();
         let WebSocketServer, WebSocket;
@@ -443,7 +431,15 @@ export function createHubProxy(opts) {
           socket.destroy();
           return true;
         }
-        if ((!loopback && !allow_remote) || !seat_key || !origin_allowed(req)) {
+        if (!gate.loopback && !allow_remote) {
+          rejectUpgrade(socket, 403, 'The hub relay answers this computer only (it authors as the operator seat).');
+          return true;
+        }
+        if (!gate.same_origin) {
+          rejectUpgrade(socket, 403, 'Cross-origin WebSocket to the hub relay refused.');
+          return true;
+        }
+        if (!seat_key) {
           socket.destroy();
           return true;
         }
@@ -451,7 +447,13 @@ export function createHubProxy(opts) {
         // one side of a string-pipe relay ships RSV1 frames the other side
         // never negotiated (live find: browsers/ws clients offer it by
         // default and the pipe corrupts).
-        if (!this._wss) this._wss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+        if (!this._wss) {
+          this._wss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+          // The 101 announces the app like every other response
+          // (X-AbstractFramework-App: continuum; mount=1).
+          const identity = `${APP_IDENTITY_HEADER}: ${identityHeaderValue(APP_ID)}`;
+          this._wss.on('headers', (headers) => headers.push(identity));
+        }
         const hub_ws_url = cfg().hub_url.replace(/^http/, 'ws') + '/ws';
         const upstream = new WebSocket(hub_ws_url, {
           headers: { Authorization: `Bearer ${seat_key}` },
@@ -532,24 +534,31 @@ export function createHubProxy(opts) {
     handle(req, res, pathname, search) {
       if (!pathname.startsWith('/api/hub/') && pathname !== '/api/hub/meta') return false;
 
-      // Socket-peer gate (entity's c1768 class, applied at the mount): this
-      // proxy authors hub messages AS THE OPERATOR, so a non-loopback peer
-      // reaching it could forge the operator's authorship. Gate on the
-      // connection's REAL peer (unforgeable), never a client-controlled
-      // header. The default 127.0.0.1 bind already prevents remote peers;
-      // this is defense-in-depth if HOST is widened deliberately.
-      const peer = String(req.socket && req.socket.remoteAddress ? req.socket.remoteAddress : '');
-      const loopback = peer === '127.0.0.1' || peer === '::1' || peer === '::ffff:127.0.0.1' || peer === '';
+      // Client gate (entity's c1768 class, applied at the mount): this
+      // proxy authors hub messages AS THE OPERATOR, so a browser on another
+      // machine could forge the operator's authorship. The client is the
+      // kit's requestContext answer (bin/request_gate.js): the socket peer,
+      // or behind the gateway's /apps/continuum/ (a loopback peer) the
+      // address the gateway forwarded — never a header from anyone else.
+      let gate;
+      try {
+        gate = request_gate(req);
+      } catch (e) {
+        if (!(e instanceof MountRequestError)) throw e;
+        res.writeHead(e.status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'bad_request', detail: e.message }));
+        return true;
+      }
       const allow_remote = cfg().allow_remote;
-      if (!loopback && !allow_remote) {
+      if (!gate.loopback && !allow_remote) {
         res.writeHead(403, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: 'hub_proxy_non_loopback', detail: `Hub proxy refuses non-loopback peer ${peer} (it authors as the operator seat). Start Continuum with --hub-allow-remote only behind a trusted front.` }));
+        res.end(JSON.stringify({ error: 'hub_proxy_non_loopback', detail: `Hub proxy refuses a browser on another machine (${gate.ctx.clientAddress}): it authors as the operator seat. Start Continuum with --hub-allow-remote only behind a trusted front.` }));
         return true;
       }
       // Cross-origin browser requests are refused even from loopback: the
       // browser is a loopback peer, and a hostile page can fire simple
       // POSTs (no preflight) at this surface. Origin-vs-Host is the gate.
-      if (!origin_allowed(req)) {
+      if (!gate.same_origin) {
         res.writeHead(403, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'hub_proxy_cross_origin', detail: 'Cross-origin requests to the hub proxy are refused (the proxy authors as the operator seat).' }));
         return true;

package/bin/request_gate.js

@@ -0,0 +1,43 @@
+/**
+ * "Is this request from this computer, and from this app's own page?" —
+ * the ONE answer every app-local privileged route uses (the hub proxy,
+ * which authors as the operator's seat, and the Settings route, which
+ * steers it).
+ *
+ * Both questions go through @abstractframework/app-server's
+ * `requestContext(req)`: behind the gateway's `/apps/continuum/` the socket
+ * peer is ALWAYS loopback (the gateway), so the socket address says nothing
+ * about the browser. The kit believes the gateway's X-Forwarded-For /
+ * X-Forwarded-Host only from a loopback peer, and answers the browser's
+ * address and the host the browser addressed.
+ *
+ *   - loopback: the BROWSER runs on this computer (`clientIsLoopback`).
+ *   - same_origin: a declared Origin names the host the browser addressed
+ *     (the forwarded host behind the gateway, else the Host header). An
+ *     absent Origin passes: a browser never omits it on a cross-origin
+ *     fetch or WebSocket handshake, so the vector this closes cannot dodge
+ *     the check.
+ *
+ * Throws MountRequestError (status 400) for a malformed forwarded header or
+ * an unknown socket peer; callers refuse the request.
+ */
+
+import { requestContext } from '@abstractframework/app-server';
+
+export function request_gate(req) {
+  const ctx = requestContext(req);
+  return { ctx, loopback: ctx.clientIsLoopback, same_origin: origin_matches(req, ctx.host) };
+}
+
+function origin_matches(req, host) {
+  const origin = String((req.headers && req.headers.origin) || '').trim();
+  if (!origin) return true;
+  let parsed;
+  try {
+    parsed = new URL(origin);
+  } catch {
+    return false;
+  }
+  const want = String(host || '').trim().toLowerCase();
+  return Boolean(want) && parsed.host.toLowerCase() === want;
+}

package/bin/server.js

@@ -0,0 +1,232 @@
+/**
+ * The AbstractContinuum HTTP server: the built console, the app-origin
+ * gateway session proxy (/api/* → the gateway), the Team page's hub proxy
+ * (/api/hub/*, HTTP + the /api/hub/ws relay) and the Settings route.
+ *
+ * Mountable under the gateway at /apps/continuum/ (the
+ * @abstractframework/app-server mount contract): every response, the
+ * WebSocket 101 included, announces `X-AbstractFramework-App: continuum;
+ * mount=1`; the page gets `<base href="<base path>/">` and `base_path`;
+ * cookies carry `Path=<base path>/`; and every "is this the operator's own
+ * computer?" check reads the kit's requestContext (bin/request_gate.js),
+ * never the socket peer. Served at `/` on its own port it works exactly as
+ * before.
+ */
+
+import * as http from 'http';
+import { createHash } from 'crypto';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join, extname } from 'path';
+import {
+  MountRequestError,
+  createGatewaySessionProxy,
+  createGatewayUrlResolver,
+  createMountedHandler,
+  injectShell,
+  rejectUpgrade,
+  requestContext,
+} from '@abstractframework/app-server';
+import { APP_ID, createHubProxy } from './hub_proxy.js';
+import { createSettingsRoute, expand_home } from './settings.js';
+
+const MIME_TYPES = {
+  '.html': 'text/html',
+  '.js': 'application/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.webmanifest': 'application/manifest+json',
+};
+
+function getMimeType(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  return MIME_TYPES[ext] || 'application/octet-stream';
+}
+
+// Content-Security-Policy for the app document (security adversary P1
+// 2026-07-16): untrusted markdown (channel files, messages, attachments)
+// renders in this app, and standard markdown allows remote images — a
+// crafted ![](https://attacker/beacon.png) would beacon the operator's IP
+// and read-timing to an external host the moment a preview opens. img-src
+// 'self' data: kills that class app-wide. script-src 'self' is a backstop
+// belt (the renderer already cannot emit script). ws:/wss: are needed
+// because 'self' does not reliably cover scheme-different WebSocket dials;
+// only our own bundle can open sockets (script-src), so this stays tight.
+const CSP = [
+  "default-src 'self'",
+  "script-src 'self'",
+  "style-src 'self' 'unsafe-inline'", // React style={} attributes
+  "img-src 'self' data:",
+  "font-src 'self' data:",
+  "connect-src 'self' ws: wss:",
+  "object-src 'none'",
+  "base-uri 'self'",
+  "form-action 'self'",
+  "frame-ancestors 'none'",
+].join('; ');
+
+/**
+ * settings: live settings (bin/settings.js createLiveSettings); distDir: the
+ * built console. The gateway URL, like the port and host, is read once from
+ * the settings at creation.
+ */
+export function createContinuumServer({ settings, distDir }) {
+  const AT_START = settings.get();
+  const DEFAULT_GATEWAY_URL = AT_START.gateway_url.value;
+  const DIST_DIR = distDir;
+  // A gateway URL nobody chose (the local gateway pointer, or the built-in
+  // default) follows the pointer while the server runs: the kit's resolver
+  // re-reads it when the gateway refuses a connection. A flag, setting or
+  // environment choice never moves.
+  const CHOSEN_GATEWAY = ['flag', 'setting', 'env'].includes(AT_START.gateway_url.source);
+
+  /**
+   * The console document for one request: the kit's injectShell puts
+   * `<base href="<base path>/">` first in <head> (every relative asset and
+   * fetch resolves under /apps/continuum/ behind the gateway, under / on the
+   * app's own port) plus `window.__ABSTRACT_UI_CONFIG__` (gateway_url,
+   * base_path) in one inline script. The CSP admits exactly that script by
+   * its hash; every other inline script stays refused.
+   */
+  function shellResponse(html, ctx) {
+    const page = injectShell(html, { basePath: ctx.basePath, config: { gateway_url: gatewaySessionProxy.defaultGatewayUrl } });
+    const inline = /<base [^>]*><script>([\s\S]*?)<\/script>/.exec(page);
+    if (!inline) throw new Error('injectShell produced no inline config script');
+    const hash = createHash('sha256').update(inline[1], 'utf8').digest('base64');
+    const csp = CSP.replace("script-src 'self'", `script-src 'self' 'sha256-${hash}'`);
+    return { page, csp };
+  }
+
+  function serveFile(res, filePath, ctx) {
+    try {
+      if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+        return false;
+      }
+      const mime = getMimeType(filePath);
+      const headers = {
+        'Content-Type': mime,
+        'Cache-Control': 'no-cache',
+        'X-Content-Type-Options': 'nosniff',
+      };
+      if (mime === 'text/html') {
+        // CSP is a document policy — attach it where a document loads.
+        const { page, csp } = shellResponse(readFileSync(filePath, 'utf8'), ctx);
+        headers['Content-Type'] = 'text/html; charset=utf-8';
+        headers['Content-Security-Policy'] = csp;
+        res.writeHead(200, headers);
+        res.end(page);
+        return true;
+      }
+      res.writeHead(200, headers);
+      res.end(readFileSync(filePath));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // Cookies abstractcontinuum_gateway_* and header x-abstractcontinuum-csrf
+  // derive from appId; mounted, the cookies carry Path=/apps/continuum/.
+  const gatewaySessionProxy = createGatewaySessionProxy({
+    appId: 'abstractcontinuum',
+    defaultGatewayUrl: CHOSEN_GATEWAY ? DEFAULT_GATEWAY_URL : createGatewayUrlResolver({}),
+  });
+
+  // Team page transport: /api/hub/* forwards an allowlisted hub API subset
+  // with the OPERATOR seat's key attached server-side (proposal c1692,
+  // agency contract c1696 — authorship stays the operator's own).
+  // Every hub setting is a getter: a seat saved on the Settings page or with
+  // `abstractcontinuum config set` applies without a restart.
+  const hubProxy = createHubProxy({
+    hubUrl: () => settings.value('hub_url'),
+    seat: () => settings.value('hub_seat'),
+    keysPath: () => expand_home(settings.value('hub_keys')),
+    token: () => settings.value('hub_token'),
+    allowRemote: () => settings.value('hub_allow_remote'),
+  });
+
+  // The Settings page's door to this server's own settings (hub seat).
+  const settingsRoute = createSettingsRoute({ live: settings });
+
+  const server = http.createServer(createMountedHandler({ appId: APP_ID }, (req, res, ctx) => {
+    // Parse against a FIXED base: a malformed Host header (e.g. "a b") makes
+    // new URL throw synchronously, which would kill the whole process from
+    // one bad request (adversarial P1 2026-07-13). The host plays no role in
+    // routing here — only the pathname does.
+    let pathname = '/';
+    let search = '';
+    try {
+      const u = new URL(req.url, 'http://local');
+      pathname = u.pathname;
+      search = u.search;
+    } catch {
+      res.writeHead(400);
+      res.end('Bad Request');
+      return;
+    }
+
+    if (settingsRoute.handle(req, res, pathname)) {
+      return;
+    }
+
+    if (hubProxy.handle(req, res, pathname, search)) {
+      return;
+    }
+
+    if (gatewaySessionProxy.handle(req, res, pathname)) {
+      return;
+    }
+
+    if (pathname.includes('..')) {
+      res.writeHead(400);
+      res.end('Bad Request');
+      return;
+    }
+
+    if (pathname === '/' || pathname === '') {
+      pathname = '/index.html';
+    }
+
+    const filePath = join(DIST_DIR, pathname);
+    if (serveFile(res, filePath, ctx)) return;
+    if (serveFile(res, filePath + '.html', ctx)) return;
+
+    // SPA fallback
+    if (serveFile(res, join(DIST_DIR, 'index.html'), ctx)) return;
+
+    res.writeHead(404);
+    res.end('Not Found');
+  }));
+
+  // Live hub updates: relay browser WebSockets to the hub with the seat key
+  // attached server-side (operator c2240 — realtime, not 5s polling).
+  server.on('upgrade', (req, socket, head) => {
+    // F7 (dm-99 tail): a raw upgrade socket with no 'error' listener is a
+    // process-killer (browser aborts mid-handshake raise uncaught 'error');
+    // and a rejected relay promise without .catch is an unhandled rejection.
+    socket.on('error', () => {
+      try { socket.destroy(); } catch { /* already gone */ }
+    });
+    // A malformed forwarded header or an unknown peer: refused before any
+    // route (the kit's rule; the hub relay applies it again for its gate).
+    try {
+      requestContext(req);
+    } catch (e) {
+      if (!(e instanceof MountRequestError)) throw e;
+      rejectUpgrade(socket, e.status, e.message);
+      return;
+    }
+    void hubProxy.handleUpgrade(req, socket, head).then((handled) => {
+      if (!handled) rejectUpgrade(socket, 404, 'No WebSocket here.');
+    }).catch(() => {
+      try { socket.destroy(); } catch { /* already gone */ }
+    });
+  });
+
+  return server;
+}